<!DOCTYPE html>
<html>

<head>
  <title>Quarkus - Using Hibernate ORM and JPA</title>
  <script id="adobe_dtm" src="https://www.redhat.com/dtm.js" type="text/javascript"></script>
  <script src="/assets/javascript/highlight.pack.js" type="text/javascript"></script>
  <META HTTP-EQUIV='Content-Security-Policy' CONTENT="default-src 'none'; script-src 'self' 'unsafe-eval' 'sha256-ANpuoVzuSex6VhqpYgsG25OHWVA1I+F6aGU04LoI+5s=' 'sha256-ipy9P/3rZZW06mTLAR0EnXvxSNcnfSDPLDuh3kzbB1w=' js.bizographics.com https://www.redhat.com assets.adobedtm.com jsonip.com https://ajax.googleapis.com https://www.googletagmanager.com https://www.google-analytics.com https://use.fontawesome.com; style-src 'self' https://fonts.googleapis.com https://use.fontawesome.com; img-src 'self' *; media-src 'self' ; frame-src https://www.googletagmanager.com https://www.youtube.com; frame-ancestors 'none'; base-uri 'none'; object-src 'none'; form-action 'none'; font-src 'self' https://use.fontawesome.com https://fonts.gstatic.com;">
  <META HTTP-EQUIV='X-Frame-Options' CONTENT="DENY">
  <META HTTP-EQUIV='X-XSS-Protection' CONTENT="1; mode=block">
  <META HTTP-EQUIV='X-Content-Type-Options' CONTENT="nosniff">
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="description" content="Quarkus: Supersonic Subatomic Java">
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@QuarkusIO"> 
  <meta name="twitter:creator" content="@QuarkusIO">
  <meta property="og:url" content="https://quarkus.io/guides/hibernate-orm" />
  <meta property="og:title" content="Quarkus - Using Hibernate ORM and JPA" />
  <meta property="og:description" content="Quarkus: Supersonic Subatomic Java" />
  <meta property="og:image" content="/assets/images/quarkus_card.png" />
  <link rel="canonical" href="https://quarkus.io/guides/hibernate-orm">
  <link rel="shortcut icon" type="image/png" href="/favicon.ico" >
  <link rel="stylesheet" href="https://quarkus.io/guides/stylesheet/config.css" />
  <link rel="stylesheet" href="/assets/css/main.css" />
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous">
  <link rel="alternate" type="application/rss+xml"  href="https://quarkus.io/feed.xml" title="Quarkus">
  <script src="https://quarkus.io/assets/javascript/goan.js" type="text/javascript"></script>
  <script src="https://quarkus.io/assets/javascript/hl.js" type="text/javascript"></script>
</head>

<body class="guides">
  <!-- Google Tag Manager (noscript) -->
  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-NJWS5L"
  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
  <!-- End Google Tag Manager (noscript) -->

  <div class="nav-wrapper">
  <div class="grid-wrapper">
    <div class="width-12-12">
      <input type="checkbox" id="checkbox" />
      <nav id="main-nav" class="main-nav">
  <div class="container">
    <div class="logo-wrapper">
      
        <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_600px_reverse.png" class="project-logo" title="Quarkus"></a>
      
    </div>
    <label class="nav-toggle" for="checkbox">
      <i class="fa fa-bars"></i>
    </label>
    <div id="menu" class="menu">
      <span>
        <a href="/get-started/" class="">Get Started</a>
      </span>
      <span>
        <a href="/guides/" class="active">Guides</a>
      </span>
      <span>
        <a href="/community/" class="">Community</a>
      </span>
      <span>
        <a href="/support/" class="">Support</a>
      </span>
      <span>
        <a href="/blog/" class="">Blog</a>
      </span>
      <span>
        <a href="https://code.quarkus.io" class="button-cta secondary white">Start Coding</a>
      </span>
    </div>
  </div>
      </nav>
    </div>
  </div>
</div>

  <div class="content">
    <div class="guide">
  <div class="width-12-12">
    <h1 class="text-caps">Quarkus - Using Hibernate ORM and JPA</h1>
    <div class="hide-mobile toc"><ul class="sectlevel1">
<li><a href="#setting-up-and-configuring-hibernate-orm">Setting up and configuring Hibernate ORM</a>
<ul class="sectlevel2">
<li><a href="#hibernate-configuration-properties">Hibernate ORM configuration properties</a></li>
</ul>
</li>
<li><a href="#setting-up-and-configuring-hibernate-orm-with-a-persistence-xml">Setting up and configuring Hibernate ORM with a <code>persistence.xml</code></a></li>
<li><a href="#defining-entities-in-external-projects-or-jars">Defining entities in external projects or jars</a></li>
<li><a href="#hibernate-orm-in-development-mode">Hibernate ORM in development mode</a></li>
<li><a href="#hibernate-orm-in-production-mode">Hibernate ORM in production mode</a></li>
<li><a href="#caching">Caching</a>
<ul class="sectlevel2">
<li><a href="#caching-of-entities">Caching of entities</a></li>
<li><a href="#caching-of-collections-and-relations">Caching of collections and relations</a></li>
<li><a href="#caching-of-queries">Caching of queries</a></li>
<li><a href="#tuning-of-cache-regions">Tuning of Cache Regions</a></li>
<li><a href="#limitations-of-caching">Limitations of Caching</a></li>
</ul>
</li>
<li><a href="#envers">Hibernate Envers</a></li>
<li><a href="#metrics">Metrics</a></li>
<li><a href="#limitations-and-other-things-you-should-know">Limitations and other things you should know</a>
<ul class="sectlevel2">
<li><a href="#automatic-build-time-enhancement">Automatic build time enhancement</a></li>
<li><a href="#automatic-integration">Automatic integration</a></li>
<li><a href="#limitations">Limitations</a></li>
<li><a href="#other-notable-differences">Other notable differences</a></li>
</ul>
</li>
<li><a href="#simplifying-hibernate-orm-with-panache">Simplifying Hibernate ORM with Panache</a></li>
<li><a href="#configure-your-datasource">Configure your datasource</a></li>
<li><a href="#multitenancy">Multitenancy</a>
<ul class="sectlevel2">
<li><a href="#writing-the-application">Writing the application</a></li>
<li><a href="#configuring-the-application">Configuring the application</a></li>
<li><a href="#programmatically-resolving-tenants-connections">Programmatically Resolving Tenants Connections</a></li>
</ul>
</li>
</ul></div>
    <div>
      <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Hibernate ORM is the de facto standard JPA implementation and offers you the full breadth of an Object Relational Mapper.
It works beautifully in Quarkus.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="setting-up-and-configuring-hibernate-orm"><a class="anchor" href="#setting-up-and-configuring-hibernate-orm"></a>Setting up and configuring Hibernate ORM</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When using Hibernate ORM in Quarkus, you don&#8217;t need to have a <code>persistence.xml</code> resource to configure it.</p>
</div>
<div class="paragraph">
<p>Using such a classic configuration file is an option, but unnecessary unless you have specific advanced needs;
so we&#8217;ll see first how Hibernate ORM can be configured without a <code>persistence.xml</code> resource.</p>
</div>
<div class="paragraph">
<p>In Quarkus, you just need to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>add your configuration settings in <code>application.properties</code></p>
</li>
<li>
<p>annotate your entities with <code>@Entity</code> and any other mapping annotation as usual</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Other configuration needs have been automated: Quarkus will make some opinionated choices and educated guesses.</p>
</div>
<div class="paragraph">
<p>Add the following dependencies to your project:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the Hibernate ORM extension: <code>io.quarkus:quarkus-hibernate-orm</code></p>
</li>
<li>
<p>your JDBC driver extension; the following options are available:</p>
<div class="ulist">
<ul>
<li>
<p><code>quarkus-jdbc-db2</code> for <a href="https://www.ibm.com/products/db2-database">IBM DB2</a></p>
</li>
<li>
<p><code>quarkus-jdbc-derby</code> for <a href="https://db.apache.org/derby/">Apache Derby</a></p>
</li>
<li>
<p><code>quarkus-jdbc-h2</code> for <a href="https://www.h2database.com/html/main.html">H2</a></p>
</li>
<li>
<p><code>quarkus-jdbc-mariadb</code> for <a href="https://mariadb.com/">MariaDB</a></p>
</li>
<li>
<p><code>quarkus-jdbc-mssql</code> for <a href="https://www.microsoft.com/en-gb/sql-server/">Microsoft SQL Server</a></p>
</li>
<li>
<p><code>quarkus-jdbc-mysql</code> for <a href="https://www.mysql.com/">MySQL</a></p>
</li>
<li>
<p><code>quarkus-jdbc-postgresql</code> for <a href="https://www.postgresql.org/">PostgreSQL</a></p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="listingblock">
<div class="title">Example dependencies using Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="xml" class="language-xml hljs">&lt;dependencies&gt;
    &lt;!-- Hibernate ORM specific dependencies --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;io.quarkus&lt;/groupId&gt;
        &lt;artifactId&gt;quarkus-hibernate-orm&lt;/artifactId&gt;
    &lt;/dependency&gt;

    &lt;!-- JDBC driver dependencies --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;io.quarkus&lt;/groupId&gt;
        &lt;artifactId&gt;quarkus-jdbc-postgresql&lt;/artifactId&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Annotate your persistent objects with <code>@Entity</code>,
then add the relevant configuration properties in <code>application.properties</code>.</p>
</div>
<div class="listingblock">
<div class="title">Example <code>application.properties</code></div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs"># datasource configuration
quarkus.datasource.db-kind = postgresql
quarkus.datasource.username = hibernate
quarkus.datasource.password = hibernate
quarkus.datasource.jdbc.url = jdbc:postgresql://localhost:5432/hibernate_db

# drop and create the database at startup (use `update` to only update the schema)
quarkus.hibernate-orm.database.generation=drop-and-create</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that these configuration properties are not the same ones as in your typical Hibernate ORM configuration file: these drive Quarkus configuration properties,
which often will map to Hibernate configuration properties but could have different names and don&#8217;t necessarily map 1:1 to each other.</p>
</div>
<div class="paragraph">
<p>Also, Quarkus will set many Hibernate configuration settings automatically, and will often use more modern defaults.</p>
</div>
<div class="paragraph">
<p>Please see below section <a href="#hibernate-configuration-properties">Hibernate ORM configuration properties</a> for the list of properties you can set in <code>application.properties</code>.</p>
</div>
<div class="paragraph">
<p>An <code>EntityManagerFactory</code> will be created based on the Quarkus <code>datasource</code> configuration as long as the Hibernate ORM extension is listed among your project dependencies.</p>
</div>
<div class="paragraph">
<p>The dialect will be selected based on the JDBC driver - unless you set one explicitly.</p>
</div>
<div class="paragraph">
<p>You can then happily inject your <code>EntityManager</code>:</p>
</div>
<div class="listingblock">
<div class="title">Example application bean using Hibernate</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@ApplicationScoped
public class SantaClausService {
    @Inject
    EntityManager em; <i class="conum" data-value="1"></i><b>(1)</b>

    @Transactional <i class="conum" data-value="2"></i><b>(2)</b>
    public void createGift(String giftDescription) {
        Gift gift = new Gift();
        gift.setName(giftDescription);
        em.persist(gift);
    }
}</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>Inject your entity manager and have fun</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>Mark your CDI bean method as <code>@Transactional</code> and the <code>EntityManager</code> will enlist and flush at commit.</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="title">Example Entity</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@Entity
public class Gift {
    private Long id;
    private String name;

    @Id @GeneratedValue(strategy = GenerationType.SEQUENCE, generator="giftSeq")
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To load some SQL statements when Hibernate ORM starts, add an <code>import.sql</code> in the root of your resources directory.
Such a script can contain any SQL DML statements; make sure to terminate each statement with a semicolon.
This is useful to have a data set ready for your tests or demos.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Make sure to wrap methods modifying your database (e.g. <code>entity.persist()</code>) within a transaction. Marking a
CDI bean method <code>@Transactional</code> will do that for you and make that method a transaction boundary. We recommend doing
so at your application entry point boundaries like your REST endpoint controllers.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="hibernate-configuration-properties"><a class="anchor" href="#hibernate-configuration-properties"></a>Hibernate ORM configuration properties</h3>
<div class="paragraph">
<p>There are various optional properties useful to refine your <code>EntityManagerFactory</code> or guide guesses of Quarkus.</p>
</div>
<div class="paragraph">
<p>There are no required properties, as long as a default datasource is configured.</p>
</div>
<div class="paragraph">
<p>When no property is set, Quarkus can typically infer everything it needs to setup Hibernate ORM
and will have it use the default datasource.</p>
</div>
<div class="paragraph">
<p>The configuration properties listed here allow you to override such defaults, and customize and tune various aspects.</p>
</div>
<div class="paragraph configuration-legend">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> Configuration property fixed at build time - All other configuration properties are overridable at runtime</p>
</div>
<table class="tableblock frame-all grid-all stretch configuration-reference searchable">
<colgroup>
<col style="width: 80%;">
<col style="width: 10%;">
<col style="width: 10%;">
</colgroup>
<tbody>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-hibernate-orm_configuration"></a><a href="#quarkus-hibernate-orm_configuration">Configuration property</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.dialect"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.dialect">quarkus.hibernate-orm.dialect</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Class name of the Hibernate ORM dialect. The complete list of bundled dialects is available in the
<a href="https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/dialect/package-summary.html">Hibernate ORM JavaDoc</a>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Not all the dialects are supported in GraalVM native executables: we currently provide driver extensions for PostgreSQL,
MariaDB, Microsoft SQL Server and H2.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.dialect.storage-engine"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.dialect.storage-engine">quarkus.hibernate-orm.dialect.storage-engine</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The storage engine to use when the dialect supports multiple storage engines.</p>
</div>
<div class="paragraph">
<p>E.g. <code>MyISAM</code> or <code>InnoDB</code> for MySQL.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.sql-load-script"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.sql-load-script">quarkus.hibernate-orm.sql-load-script</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Name of the file containing the SQL statements to execute when Hibernate ORM starts.
Its default value differs depending on the Quarkus launch mode:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>In dev and test modes, it defaults to <code>import.sql</code>.
Simply add an <code>import.sql</code> file in the root of your resources directory
and it will be picked up without having to set this property.
Pass <code>no-file</code> to force Hibernate ORM to ignore the SQL import file.</p>
</li>
<li>
<p>In production mode, it defaults to <code>no-file</code>.
It means Hibernate ORM won&#8217;t try to execute any SQL import file by default.
Pass an explicit value to force Hibernate ORM to execute the SQL import file.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If you need different SQL statements between dev mode, test (<code>@QuarkusTest</code>) and in production, use Quarkus
<a href="https://quarkus.io/guides/config#configuration-profiles">configuration profiles facility</a>.</p>
</div>
<div class="listingblock">
<div class="title">application.properties</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="property" class="language-property hljs">%dev.quarkus.hibernate-orm.sql-load-script = import-dev.sql
%test.quarkus.hibernate-orm.sql-load-script = import-test.sql
%prod.quarkus.hibernate-orm.sql-load-script = no-file</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Quarkus supports <code>.sql</code> file with SQL statements or comments spread over multiple lines.
Each SQL statement must be terminated by a semicolon.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>import.sql in DEV, TEST ; no-file otherwise</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.batch-fetch-size"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.batch-fetch-size">quarkus.hibernate-orm.batch-fetch-size</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The size of the batches used when loading entities and collections.</p>
</div>
<div class="paragraph">
<p><code>-1</code> means batch loading is disabled. This is the default.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">int</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>-1</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.physical-naming-strategy"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.physical-naming-strategy">quarkus.hibernate-orm.physical-naming-strategy</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Pluggable strategy contract for applying physical naming rules for database object names. Class name of the Hibernate PhysicalNamingStrategy implementation</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.implicit-naming-strategy"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.implicit-naming-strategy">quarkus.hibernate-orm.implicit-naming-strategy</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Pluggable strategy for applying implicit naming rules when an explicit name is not given. Class name of the Hibernate ImplicitNamingStrategy implementation</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.multitenant"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.multitenant">quarkus.hibernate-orm.multitenant</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Defines the method for multi-tenancy (DATABASE, NONE, SCHEMA). The complete list of allowed values is available in the
<a href="https://docs.jboss.org/hibernate/stable/orm/javadocs/org/hibernate/MultiTenancyStrategy.html">Hibernate ORM JavaDoc</a>.
The type DISCRIMINATOR is currently not supported. The default value is NONE (no multi-tenancy).</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.multitenant-schema-datasource"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.multitenant-schema-datasource">quarkus.hibernate-orm.multitenant-schema-datasource</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Defines the name of the data source to use in case of SCHEMA approach. The default data source will be used if not set.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.statistics"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.statistics">quarkus.hibernate-orm.statistics</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Whether statistics collection is enabled. If 'metrics.enabled' is true, then the default here is considered true, otherwise the default is false.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.metrics.enabled"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.metrics.enabled">quarkus.hibernate-orm.metrics.enabled</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Whether or not metrics are published if a metrics extension is enabled.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.second-level-caching-enabled"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.second-level-caching-enabled">quarkus.hibernate-orm.second-level-caching-enabled</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The default in Quarkus is for 2nd level caching to be enabled, and a good implementation is already integrated for you.
 Just cherry-pick which entities should be using the cache.
 Set this to false to disable all 2nd level caches.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>true</code></p></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-hibernate-orm_quarkus.hibernate-orm.query"></a><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.query">Query related configuration</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.query.query-plan-cache-max-size"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.query.query-plan-cache-max-size">quarkus.hibernate-orm.query.query-plan-cache-max-size</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The maximum size of the query plan cache.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.query.default-null-ordering"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.query.default-null-ordering">quarkus.hibernate-orm.query.default-null-ordering</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Default precedence of null values in <code>ORDER BY</code> clauses.</p>
</div>
<div class="paragraph">
<p>Valid values are: <code>none</code>, <code>first</code>, <code>last</code>.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-hibernate-orm_quarkus.hibernate-orm.database"></a><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.database">Database related configuration</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.database.generation"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.database.generation">quarkus.hibernate-orm.database.generation</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Select whether the database schema is generated or not. <code>drop-and-create</code> is awesome in development mode. Accepted values: <code>none</code>, <code>create</code>, <code>drop-and-create</code>, <code>drop</code>, <code>update</code>.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>none</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.database.generation.halt-on-error"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.database.generation.halt-on-error">quarkus.hibernate-orm.database.generation.halt-on-error</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Whether we should stop on the first error when applying the schema.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.database.default-catalog"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.database.default-catalog">quarkus.hibernate-orm.database.default-catalog</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The default catalog to use for the database objects.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.database.default-schema"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.database.default-schema">quarkus.hibernate-orm.database.default-schema</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The default schema to use for the database objects.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.database.charset"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.database.charset">quarkus.hibernate-orm.database.charset</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The charset of the database.
 Used for DDL generation and also for the SQL import scripts.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><a href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">Charset</a></p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>UTF-8</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.database.globally-quoted-identifiers"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.database.globally-quoted-identifiers">quarkus.hibernate-orm.database.globally-quoted-identifiers</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Whether Hibernate should quote all identifiers.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc"></a><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc">JDBC related configuration</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc.timezone"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc.timezone">quarkus.hibernate-orm.jdbc.timezone</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The time zone pushed to the JDBC driver.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc.statement-fetch-size"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc.statement-fetch-size">quarkus.hibernate-orm.jdbc.statement-fetch-size</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>How many rows are fetched at a time by the JDBC driver.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">int</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc.statement-batch-size"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.jdbc.statement-batch-size">quarkus.hibernate-orm.jdbc.statement-batch-size</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The number of updates (inserts, updates and deletes) that are sent by the JDBC driver at one time for execution.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">int</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-hibernate-orm_quarkus.hibernate-orm.log"></a><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.log">Logging configuration</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.log.sql"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.log.sql">quarkus.hibernate-orm.log.sql</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Show SQL logs and format them nicely.
 Setting it to true is obviously not recommended in production.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.log.bind-param"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.log.bind-param">quarkus.hibernate-orm.log.bind-param</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Logs SQL bind parameter.
 Setting it to true is obviously not recommended in production.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.log.jdbc-warnings"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.log.jdbc-warnings">quarkus.hibernate-orm.log.jdbc-warnings</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>Whether JDBC warnings should be collected and logged.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>depends on dialect</code></p></td>
</tr>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-hibernate-orm_quarkus.hibernate-orm.cache"></a><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.cache">Caching configuration</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.cache.-cache-.expiration.max-idle"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.cache.-cache-.expiration.max-idle">quarkus.hibernate-orm.cache."cache".expiration.max-idle</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The maximum time before an object of the cache is considered expired.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><a href="https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html">Duration</a>
  <a href="#duration-note-anchor" title="More information about the Duration format"><span class="icon"><i class="fa fa-question-circle"></i></span></a></p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-hibernate-orm_quarkus.hibernate-orm.cache.-cache-.memory.object-count"></a><code><a href="#quarkus-hibernate-orm_quarkus.hibernate-orm.cache.-cache-.memory.object-count">quarkus.hibernate-orm.cache."cache".memory.object-count</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The maximum number of objects kept in memory in the cache.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">long</p></td>
<td class="tableblock halign-left valign-middle"></td>
</tr>
</tbody>
</table>
<div id="duration-note-anchor" class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="title">About the Duration format</div>
<div class="paragraph">
<p>The format for durations uses the standard <code>java.time.Duration</code> format.
You can learn more about it in the <a href="https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-">Duration#parse() javadoc</a>.</p>
</div>
<div class="paragraph">
<p>You can also provide duration values starting with a number.
In this case, if the value consists only of a number, the converter treats the value as seconds.
Otherwise, <code>PT</code> is implicitly prepended to the value to obtain a standard <code>java.time.Duration</code> format.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Do not mix <code>persistence.xml</code> and <code>quarkus.hibernate-orm.*</code> properties in <code>application.properties</code>.
Quarkus will raise an exception.
Make up your mind on which approach you want to use.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Want to start a PostgreSQL server on the side with Docker?</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">docker run --ulimit memlock=-1:-1 -it --rm=true --memory-swappiness=0 \
           --name postgres-quarkus-hibernate -e POSTGRES_USER=hibernate \
           -e POSTGRES_PASSWORD=hibernate -e POSTGRES_DB=hibernate_db \
           -p 5432:5432 postgres:10.5</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will start a non-durable empty database: ideal for a quick experiment!</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="setting-up-and-configuring-hibernate-orm-with-a-persistence-xml"><a class="anchor" href="#setting-up-and-configuring-hibernate-orm-with-a-persistence-xml"></a>Setting up and configuring Hibernate ORM with a <code>persistence.xml</code></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Alternatively, you can use a <code>META-INF/persistence.xml</code> to setup Hibernate ORM.
This is useful for:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>migrating existing code</p>
</li>
<li>
<p>when you have relatively complex settings requiring the full flexibility of the configuration</p>
</li>
<li>
<p>or if you like it the good old way</p>
</li>
</ul>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>If you have a <code>persistence.xml</code>, then you cannot use the <code>quarkus.hibernate-orm.*</code> properties
and only persistence units defined in <code>persistence.xml</code> will be taken into account.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Your <code>pom.xml</code> dependencies as well as your Java code would be identical to the precedent example. The only
difference is that you would specify your Hibernate ORM configuration in <code>META-INF/persistence.xml</code>:</p>
</div>
<div class="listingblock">
<div class="title">Example persistence.xml resource</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="xml" class="language-xml hljs">&lt;persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
             http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
             version="2.1"&gt;

    &lt;persistence-unit name="CustomerPU" transaction-type="JTA"&gt;

        &lt;description&gt;My customer entities&lt;/description&gt;

        &lt;properties&gt;
            &lt;!-- Connection specific --&gt;
            &lt;property name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQL95Dialect"/&gt;

            &lt;property name="hibernate.show_sql" value="true"/&gt;
            &lt;property name="hibernate.format_sql" value="true"/&gt;

            &lt;!--
                Optimistically create the tables;
                will cause background errors being logged if they already exist,
                but is practical to retain existing data across runs (or create as needed) --&gt;
            &lt;property name="javax.persistence.schema-generation.database.action" value="drop-and-create"/&gt;

            &lt;property name="javax.persistence.validation.mode" value="NONE"/&gt;
        &lt;/properties&gt;

    &lt;/persistence-unit&gt;
&lt;/persistence&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>When using the <code>persistence.xml</code> configuration you are configuring Hibernate ORM directly,
so in this case the appropriate reference is the <a href="https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#configurations">documentation on hibernate.org</a>.</p>
</div>
<div class="paragraph">
<p>Please remember these are not the same property names as the ones used in the Quarkus <code>application.properties</code>, nor will
the same defaults be applied.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="defining-entities-in-external-projects-or-jars"><a class="anchor" href="#defining-entities-in-external-projects-or-jars"></a>Defining entities in external projects or jars</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Hibernate ORM in Quarkus relies on compile-time bytecode enhancements to your entities. If you define your entities in the
same project where you build your Quarkus application, everything will work fine.</p>
</div>
<div class="paragraph">
<p>If the entities come from external projects
or jars, you can make sure that your jar is treated like a Quarkus application library by adding an empty <code>META-INF/beans.xml</code> file.</p>
</div>
<div class="paragraph">
<p>This will allow Quarkus to index and enhance your entities as if they were inside the current project.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="hibernate-orm-in-development-mode"><a class="anchor" href="#hibernate-orm-in-development-mode"></a>Hibernate ORM in development mode</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus development mode is really useful for applications that mix front end or services and database access.</p>
</div>
<div class="paragraph">
<p>There are a few common approaches to make the best of it.</p>
</div>
<div class="paragraph">
<p>The first choice is to use <code>quarkus.hibernate-orm.database.generation=drop-and-create</code> in conjunction with <code>import.sql</code>.</p>
</div>
<div class="paragraph">
<p>That way for every change to your app and in particular to your entities, the database schema will be properly recreated
and your data fixture (stored in <code>import.sql</code>) will be used to repopulate it from scratch.
This is best to perfectly control your environment and works magic with Quarkus live reload mode:
your entity changes or any change to your <code>import.sql</code> is immediately picked up and the schema updated without restarting the application!</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>By default in <code>dev</code> and <code>test</code> modes, Hibernate ORM, upon boot, will read and execute the SQL statements in the <code>/import.sql</code> file (if present).
You can change the file name by changing the property <code>quarkus.hibernate-orm.sql-load-script</code> in <code>application.properties</code>.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The second approach is to use <code>quarkus.hibernate-orm.database.generation=update</code>.
This approach is best when you do many entity changes but
still need to work on a copy of the production data
or if you want to reproduce a bug that is based on specific database entries.
<code>update</code> is a best effort from Hibernate ORM and will fail in specific situations
including altering your database structure which could lead to data loss.
For example if you change structures which violate a foreign key constraint, Hibernate ORM might have to bail out.
But for development, these limitations are acceptable.</p>
</div>
<div class="paragraph">
<p>The third approach is to use <code>quarkus.hibernate-orm.database.generation=none</code>.
This approach is best when you are working on a copy of the production data but want to fully control the schema evolution.
Or if you use a database schema migration tool like <a href="https://quarkus.io/guides/flyway">Flyway</a>.</p>
</div>
<div class="paragraph">
<p>With this approach when making changes to an entity, make sure to adapt the database schema accordingly;
you could also use <code>validate</code> to have Hibernate verify the schema matches its expectations.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Do not use <code>quarkus.hibernate-orm.database.generation</code> <code>drop-and-create</code> and <code>update</code> in your production environment.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>These approaches become really powerful when combined with Quarkus configuration profiles.
You can define different <a href="https://quarkus.io/guides/config#configuration-profiles">configuration profiles</a>
to select different behaviors depending on your environment.
This is great because you can define different combinations of Hibernate ORM properties matching the development style you currently need.</p>
</div>
<div class="listingblock">
<div class="title">application.properties</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">%dev.quarkus.hibernate-orm.database.generation = drop-and-create
%dev.quarkus.hibernate-orm.sql-load-script = import-dev.sql

%dev-with-data.quarkus.hibernate-orm.database.generation = update
%dev-with-data.quarkus.hibernate-orm.sql-load-script = no-file

%prod.quarkus.hibernate-orm.database.generation = none
%prod.quarkus.hibernate-orm.sql-load-script = no-file</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Start "dev mode" using a custom profile via Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="bash" class="language-bash hljs">./mvnw compile quarkus:dev -Dquarkus.profile=dev-with-data</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="hibernate-orm-in-production-mode"><a class="anchor" href="#hibernate-orm-in-production-mode"></a>Hibernate ORM in production mode</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus comes with default profiles (<code>dev</code>, <code>test</code> and <code>prod</code>).
And you can add your own custom profiles to describe various environments (<code>staging</code>, <code>prod-us</code>, etc).</p>
</div>
<div class="paragraph">
<p>The Hibernate ORM Quarkus extension sets some default configurations differently in dev and test modes than in other environments.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>quarkus.hibernate-orm.sql-load-script</code> is set to <code>no-file</code> for all profiles except the <code>dev</code> and <code>test</code> ones.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can override it in your <code>application.properties</code> explicitly
(e.g. <code>%prod.quarkus.hibernate-orm.sql-load-script = import.sql</code>)
but we wanted you to avoid overriding your database by accident in prod :)</p>
</div>
<div class="paragraph">
<p>Speaking of, make sure to not drop your database schema in production!
Add the following in your properties file.</p>
</div>
<div class="listingblock">
<div class="title">application.properties</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">%prod.quarkus.hibernate-orm.database.generation = none
%prod.quarkus.hibernate-orm.sql-load-script = no-file</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="caching"><a class="anchor" href="#caching"></a>Caching</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Applications that frequently read the same entities can see their performance improved when the Hibernate ORM second-level cache is enabled.</p>
</div>
<div class="sect2">
<h3 id="caching-of-entities"><a class="anchor" href="#caching-of-entities"></a>Caching of entities</h3>
<div class="paragraph">
<p>To enable second-level cache, mark the entities that you want cached with <code>@javax.persistence.Cacheable</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@Entity
@Cacheable
public class Country {
    int dialInCode;
    // ...
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>When an entity is annotated with <code>@Cacheable</code>, all its field values are cached except for collections and relations to other entities.</p>
</div>
<div class="paragraph">
<p>This means the entity can be loaded without querying the database, but be careful as it implies the loaded entity might not reflect recent changes in the database.</p>
</div>
</div>
<div class="sect2">
<h3 id="caching-of-collections-and-relations"><a class="anchor" href="#caching-of-collections-and-relations"></a>Caching of collections and relations</h3>
<div class="paragraph">
<p>Collections and relations need to be individually annotated to be cached; in this case the Hibernate specific <code>@org.hibernate.annotations.Cache</code> should be used, which requires also to specify the <code>CacheConcurrencyStrategy</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">package org.acme;

@Entity
@Cacheable
public class Country {
    // ...

    @OneToMany
    @Cache(usage = CacheConcurrencyStrategy.READ_ONLY)
    List&lt;City&gt; cities;

    // ...
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="caching-of-queries"><a class="anchor" href="#caching-of-queries"></a>Caching of queries</h3>
<div class="paragraph">
<p>Queries can also benefit from second-level caching. Cached query results can be returned immediately to the caller, avoiding to run the query on the database.</p>
</div>
<div class="paragraph">
<p>Be careful as this implies the results might not reflect recent changes.</p>
</div>
<div class="paragraph">
<p>To cache a query, mark it as cacheable on the <code>Query</code> instance:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">Query query = ...
query.setHint("org.hibernate.cacheable", Boolean.TRUE);</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you have a <code>NamedQuery</code> then you can enable caching directly on its definition, which will usually be on an entity:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@Entity
@NamedQuery(name = "Fruits.findAll",
      query = "SELECT f FROM Fruit f ORDER BY f.name",
      hints = @QueryHint(name = "org.hibernate.cacheable", value = "true") )
public class Fruit {
   ...</code></pre>
</div>
</div>
<div class="paragraph">
<p>That&#8217;s all! Caching technology is already integrated and enabled by default in Quarkus, so it&#8217;s enough to set which ones are safe to be cached.</p>
</div>
</div>
<div class="sect2">
<h3 id="tuning-of-cache-regions"><a class="anchor" href="#tuning-of-cache-regions"></a>Tuning of Cache Regions</h3>
<div class="paragraph">
<p>Caches store the data in separate regions to isolate different portions of data; such regions are assigned a name, which is useful for configuring each region independently, or to monitor their statistics.</p>
</div>
<div class="paragraph">
<p>By default entities are cached in regions named after their fully qualified name, e.g. <code>org.acme.Country</code>.</p>
</div>
<div class="paragraph">
<p>Collections are cached in regions named after the fully qualified name of their owner entity and collection field name, separated by <code>#</code> character, e.g. <code>org.acme.Country#cities</code>.</p>
</div>
<div class="paragraph">
<p>All cached queries are by default kept in a single region dedicated to them called <code>default-query-results-region</code>.</p>
</div>
<div class="paragraph">
<p>All regions are bounded by size and time by default. The defaults are <code>10000</code> max entries, and <code>100</code> seconds as maximum idle time.</p>
</div>
<div class="paragraph">
<p>The size of each region can be customized via the <code>quarkus.hibernate-orm.cache."&lt;region_name&gt;".memory.object-count</code> property (Replace <em>&lt;region_name&gt;</em> with the actual region name).</p>
</div>
<div class="paragraph">
<p>To set the maximum idle time, provide the duration (see note on duration&#8217;s format below) via the <code>quarkus.hibernate-orm.cache."&lt;region_name&gt;".expiration.max-idle</code> property (Replace <em>&lt;region_name&gt;</em> with the actual region name).</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The double quotes are mandatory if your region name contains a dot. For instance:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">quarkus.hibernate-orm.cache."org.acme.MyEntity".memory.object-count=1000</code></pre>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The format for durations uses the standard <code>java.time.Duration</code> format.
You can learn more about it in the <a href="https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence-">Duration#parse() javadoc</a>.</p>
</div>
<div class="paragraph">
<p>You can also provide duration values starting with a number.
In this case, if the value consists only of a number, the converter treats the value as seconds.
Otherwise, <code>PT</code> is implicitly prepended to the value to obtain a standard <code>java.time.Duration</code> format.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="limitations-of-caching"><a class="anchor" href="#limitations-of-caching"></a>Limitations of Caching</h3>
<div class="paragraph">
<p>The caching technology provided within Quarkus is currently quite rudimentary and limited.</p>
</div>
<div class="paragraph">
<p>The team thought it was better to have <em>some</em> caching capability to start with, than having nothing; you can expect better caching solution to be integrated in future releases, and any help and feedback in this area is very welcome.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>These caches are kept locally, so they are not invalidated or updated when changes are made to the persistent store by other applications.</p>
</div>
<div class="paragraph">
<p>Also, when running multiple copies of the same application (in a cluster, for example on Kubernetes/OpenShift), caches in separate copies of the application aren&#8217;t synchronized.</p>
</div>
<div class="paragraph">
<p>For these reasons, enabling caching is only suitable when certain assumptions can be made: we strongly recommend that only entities, collections and queries which never change are cached. Or at most, that when indeed such an entity is mutated and allowed to be read out of date (stale) this has no impact on the expectations of the application.</p>
</div>
<div class="paragraph">
<p>Following this advice guarantees applications get the best performance out of the second-level cache and yet avoid unexpected behaviour.</p>
</div>
<div class="paragraph">
<p>On top of immutable data, in certain contexts it might be acceptable to enable caching also on mutable data; this could be a necessary tradeoff on selected
 entities which are read frequently and for which some degree of staleness is acceptable; this " acceptable degree of staleness" can be tuned by setting eviction properties.
 This is however not recommended and should be done with extreme care, as it might
 produce unexpected and unforeseen effects on the data.</p>
</div>
<div class="paragraph">
<p>Rather than enabling caching on mutable data, ideally a better solution would be to use a clustered cache; however at this time Quarkus doesn&#8217;t provide any such implementation: feel free to get in touch and let this need known so that the team can take this into account.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Finally, the second-level cache can be disabled globally by setting <code>hibernate.cache.use_second_level_cache</code> to <code>false</code>; this is a setting that needs to be specified in the <code>persistence.xml</code> configuration file.</p>
</div>
<div class="paragraph">
<p>When second-level cache is disabled, all cache annotations are ignored and all queries are run ignoring caches; this is generally useful only to diagnose issues.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="envers"><a class="anchor" href="#envers"></a>Hibernate Envers</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Envers extension to Hibernate ORM aims to provide an easy auditing / versioning solution for entity classes.</p>
</div>
<div class="paragraph">
<p>In Quarkus, Envers has a dedicated Quarkus Extension <code>io.quarkus:quarkus-hibernate-envers</code>; you just need to add this to your project to start using it.</p>
</div>
<div class="listingblock">
<div class="title">Additional dependency to enable Hibernate Envers</div>
<div class="content">
<pre class="highlightjs highlight"><code data-lang="xml" class="language-xml hljs">    &lt;!-- Add the Hibernate Envers extension --&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;io.quarkus&lt;/groupId&gt;
        &lt;artifactId&gt;quarkus-hibernate-envers&lt;/artifactId&gt;
    &lt;/dependency&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point the extension does not expose additional configuration properties.</p>
</div>
<div class="paragraph">
<p>For more information about Hibernate Envers, see <a href="https://hibernate.org/orm/envers/">hibernate.org/orm/envers/</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="metrics"><a class="anchor" href="#metrics"></a>Metrics</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The SmallRye Metrics extension is capable of exposing metrics that Hibernate ORM collects at runtime. To enable exposure of Hibernate metrics
on the <code>/metrics</code> endpoint, make sure your project depends on the <code>quarkus-smallrye-metrics</code> artifact and set the configuration property <code>quarkus.hibernate-orm.metrics.enabled</code> to <code>true</code>.
Metrics will then be available under the <code>vendor</code> scope.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="limitations-and-other-things-you-should-know"><a class="anchor" href="#limitations-and-other-things-you-should-know"></a>Limitations and other things you should know</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus does not modify the libraries it uses; this rule applies to Hibernate ORM as well: when using
this extension you will mostly have the same experience as using the original library.</p>
</div>
<div class="paragraph">
<p>But while they share the same code, Quarkus does configure some components automatically and injects custom implementations
for some extension points; this should be transparent and useful but if you&#8217;re an expert of Hibernate you might want to
know what is being done.</p>
</div>
<div class="sect2">
<h3 id="automatic-build-time-enhancement"><a class="anchor" href="#automatic-build-time-enhancement"></a>Automatic build time enhancement</h3>
<div class="paragraph">
<p>Hibernate ORM can use build time enhanced entities; normally this is not mandatory but it&#8217;s useful and will have your
applications perform better.</p>
</div>
<div class="paragraph">
<p>Typically you would need to adapt your build scripts to include the Hibernate Enhancement plugins; in Quarkus this is
not necessary as the enhancement step is integrated in the build and analysis of the Quarkus application.</p>
</div>
</div>
<div class="sect2">
<h3 id="automatic-integration"><a class="anchor" href="#automatic-integration"></a>Automatic integration</h3>
<div class="dlist">
<dl>
<dt class="hdlist1">Transaction Manager integration</dt>
<dd>
<p>You don&#8217;t need to set this up, Quarkus automatically injects the reference to the Narayana Transaction Manager.
The dependency is included automatically as a transitive dependency of the Hibernate ORM extension.
All configuration is optional; for more details see <a href="transaction">Using Transactions in Quarkus</a>.</p>
</dd>
<dt class="hdlist1">Connection pool</dt>
<dd>
<p>Don&#8217;t need to choose one either. Quarkus automatically includes the Agroal connection pool;
just configure your datasource as in the above examples and it will setup Hibernate ORM to use Agroal.
More details about this connection pool can be found in <a href="datasource">Quarkus - Datasources</a>.</p>
</dd>
<dt class="hdlist1">Second Level Cache</dt>
<dd>
<p>as explained above in section <a href="#caching">Caching</a>, you don&#8217;t need to pick an implementation.
A suitable implementation based on technologies from <a href="https://infinispan.org/">Infinispan</a> and <a href="https://github.com/ben-manes/caffeine">Caffeine</a> is included as a transitive dependency of the Hibernate ORM extension, and automatically integrated during the build.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="limitations"><a class="anchor" href="#limitations"></a>Limitations</h3>
<div class="dlist">
<dl>
<dt class="hdlist1">XML mapping</dt>
<dd>
<p>Hibernate ORM allows to map entities using XML files; this capability isn&#8217;t enabled in Quarkus: use annotations instead
as Quarkus can handle them very efficiently.
This limitation could be lifted in the future, if there&#8217;s a compelling need for it and if someone contributes it.</p>
</dd>
<dt class="hdlist1">JMX</dt>
<dd>
<p>Management beans are not working in GraalVM native images;
therefore Hibernate&#8217;s capability to register statistics and management operations with the JMX bean is disabled when compiling into a native image.
This limitation is likely permanent, as it&#8217;s not a goal for native images
to implement support for JMX. All such metrics can be accessed in other ways.</p>
</dd>
<dt class="hdlist1">JACC Integration</dt>
<dd>
<p>Hibernate ORM&#8217;s capability to integrate with JACC is disabled when building GraalVM native images,
as JACC is not available - nor useful - in native mode.</p>
</dd>
<dt class="hdlist1">Binding the Session to ThreadLocal context</dt>
<dd>
<p>Essentially using the <code>ThreadLocalSessionContext</code> helper of Hibernate ORM is not implemented.
The team believes this isn&#8217;t a big deal as it&#8217;s trivial to inject the Session via CDI instead, or
handling the binding into a ThreadLocal yourself, making this a legacy feature.
This limitation might be resolved in the future, if someone opens a ticket for it and provides a reasonable use case to justify the need.</p>
</dd>
<dt class="hdlist1">JPA Callbacks</dt>
<dd>
<p>Annotations allowing for application callbacks on entity lifecycle events defined by JPA such as <code>@javax.persistence.PostUpdate</code>, <code>@javax.persistence.PostLoad</code>, <code>@javax.persistence.PostPersist</code>, etc&#8230;&#8203; are currently not processed.
This limitation could be resolved in a future version, depending on user demand.</p>
</dd>
<dt class="hdlist1">Single instance</dt>
<dd>
<p>It is currently not possible to configure more than one instance of Hibernate ORM.
This is a temporary limitation, the team is working on it - please be patient!</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="other-notable-differences"><a class="anchor" href="#other-notable-differences"></a>Other notable differences</h3>
<div class="dlist">
<dl>
<dt class="hdlist1">Format of <code>import.sql</code></dt>
<dd>
<p>When importing a <code>import.sql</code> to setup your database, keep in mind that Quarkus reconfigures Hibernate ORM so to require a semicolon (';') to terminate each statement.
The default in Hibernate is to have a statement per line, without requiring a terminator other than newline: remember to convert your scripts to use the ';' terminator character if you&#8217;re reusing existing scripts.
This is useful so to allow multi-line statements and human friendly formatting.</p>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="simplifying-hibernate-orm-with-panache"><a class="anchor" href="#simplifying-hibernate-orm-with-panache"></a>Simplifying Hibernate ORM with Panache</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <a href="hibernate-orm-panache">Hibernate ORM with Panache</a> extension facilitates the usage of Hibernate ORM by providing active record style entities (and repositories) and focuses on making your entities trivial and fun to write in Quarkus.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configure-your-datasource"><a class="anchor" href="#configure-your-datasource"></a>Configure your datasource</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Datasource configuration is extremely simple, but is covered in a different guide as technically
it&#8217;s implemented by the Agroal connection pool extension for Quarkus.</p>
</div>
<div class="paragraph">
<p>Jump over to <a href="datasource">Quarkus - Datasources</a> for all details.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="multitenancy"><a class="anchor" href="#multitenancy"></a>Multitenancy</h2>
<div class="sectionbody">
<div class="paragraph">
<p>"The term multitenancy, in general, is applied to software development to indicate an architecture in which a single running instance of an application simultaneously serves multiple clients (tenants). This is highly common in SaaS solutions. Isolating information (data, customizations, etc.) pertaining to the various tenants is a particular challenge in these systems. This includes the data owned by each tenant stored in the database" (<a href="https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#multitenacy">Hibernate User Guide</a>).</p>
</div>
<div class="paragraph">
<p>Quarkus currently supports the <a href="https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#multitenacy-separate-database">separate database</a> and the <a href="https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#multitenacy-separate-schema">separate schema</a> approach.</p>
</div>
<div class="sect2">
<h3 id="writing-the-application"><a class="anchor" href="#writing-the-application"></a>Writing the application</h3>
<div class="paragraph">
<p>Let&#8217;s start by implementing the <code>/{tenant}</code> endpoint. As you can see from the source code below it is just a regular JAX-RS resource:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;
import javax.persistence.EntityManager;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@ApplicationScoped
@Produces("application/json")
@Consumes("application/json")
@Path("/{tenant}")
public class FruitResource {

    @Inject
    EntityManager entityManager;

    @GET
    @Path("fruits")
    public Fruit[] getFruits() {
        return entityManager.createNamedQuery("Fruits.findAll", Fruit.class)
                .getResultList().toArray(new Fruit[0]);
    }

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In order to resolve the tenant from incoming requests and map it to a specific tenant configuration, you need to create an implementation for the <code>io.quarkus.hibernate.orm.runtime.tenant.TenantResolver</code> interface.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">import javax.enterprise.context.ApplicationScoped;

import io.quarkus.arc.Arc;
import io.quarkus.arc.Unremovable;
import io.quarkus.hibernate.orm.runtime.tenant.TenantResolver;
import io.vertx.ext.web.RoutingContext;

@RequestScoped
@Unremovable
public class CustomTenantResolver implements TenantResolver {

    @Inject
    RoutingContext context;

    @Override
    public String getDefaultTenantId() {
        return "base";
    }

    @Override
    public String resolveTenantId() {
        String path = context.request().path();
        String[] parts = path.split("/");

        if (parts.length == 0) {
            // resolve to default tenant config
            return getDefaultTenantId();
        }

        return parts[1];
    }

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>From the implementation above, tenants are resolved from the request path so that in case no tenant could be inferred, the default tenant identifier is returned.</p>
</div>
</div>
<div class="sect2">
<h3 id="configuring-the-application"><a class="anchor" href="#configuring-the-application"></a>Configuring the application</h3>
<div class="paragraph">
<p>In general it is not possible to use the Hibernate ORM database generation feature in conjunction with a multitenancy setup.
Therefore you have to disable it and you need to make sure that the tables are created per schema.
The following setup will use the <a href="https://quarkus.io/guides/flyway">Flyway</a> extension to achieve this goal.</p>
</div>
<div class="sect3">
<h4 id="schema-approach"><a class="anchor" href="#schema-approach"></a>SCHEMA approach</h4>
<div class="paragraph">
<p>The same data source will be used for all tenants and a schema has to be created for every tenant inside that data source.
CAUTION: Some databases like MariaDB/MySQL do not support database schemas. In these cases you have to use the DATABASE approach below.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs"># Disable generation
quarkus.hibernate-orm.database.generation=none

# Enable SCHEMA approach and use default datasource
quarkus.hibernate-orm.multitenant=SCHEMA
# You could use a non-default datasource by using the following setting
# quarkus.hibernate-orm.multitenant-schema-datasource=other

# The default data source used for all tenant schemas
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=quarkus_test
quarkus.datasource.password=quarkus_test
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test

# Enable Flyway configuration to create schemas
quarkus.flyway.schemas=base,mycompany
quarkus.flyway.locations=classpath:schema
quarkus.flyway.migrate-at-start=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here is an example of the Flyway SQL (<code>V1.0.0__create_fruits.sql</code>) to be created in the configured folder <code>src/main/resources/schema</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="sql" class="language-sql hljs">CREATE SEQUENCE base.known_fruits_id_seq;
SELECT setval('base."known_fruits_id_seq"', 3);
CREATE TABLE base.known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO base.known_fruits(id, name) VALUES (1, 'Cherry');
INSERT INTO base.known_fruits(id, name) VALUES (2, 'Apple');
INSERT INTO base.known_fruits(id, name) VALUES (3, 'Banana');

CREATE SEQUENCE mycompany.known_fruits_id_seq;
SELECT setval('mycompany."known_fruits_id_seq"', 3);
CREATE TABLE mycompany.known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO mycompany.known_fruits(id, name) VALUES (1, 'Avocado');
INSERT INTO mycompany.known_fruits(id, name) VALUES (2, 'Apricots');
INSERT INTO mycompany.known_fruits(id, name) VALUES (3, 'Blackberries');</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="database-approach"><a class="anchor" href="#database-approach"></a>DATABASE approach</h4>
<div class="paragraph">
<p>For every tenant you need to create a named data source with the same identifier that is returned by the <code>TenantResolver</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs"># Disable generation
quarkus.hibernate-orm.database.generation=none

# Enable DATABASE approach
quarkus.hibernate-orm.multitenant=DATABASE

# Default tenant 'base'
quarkus.datasource.base.db-kind=postgresql
quarkus.datasource.base.username=quarkus_test
quarkus.datasource.base.password=quarkus_test
quarkus.datasource.base.jdbc.url=jdbc:postgresql://localhost:5432/quarkus_test

# Tenant 'mycompany'
quarkus.datasource.mycompany.db-kind=postgresql
quarkus.datasource.mycompany.username=mycompany
quarkus.datasource.mycompany.password=mycompany
quarkus.datasource.mycompany.jdbc.url=jdbc:postgresql://localhost:5433/mycompany

# Flyway configuration for the default datasource
quarkus.flyway.locations=classpath:database/default
quarkus.flyway.migrate-at-start=true

# Flyway configuration for the mycompany datasource
quarkus.flyway.mycompany.locations=classpath:database/mycompany
quarkus.flyway.mycompany.migrate-at-start=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>Following are examples of the Flyway SQL files to be created in the configured folder <code>src/main/resources/database</code>.</p>
</div>
<div class="paragraph">
<p>Default schema (<code>src/main/resources/database/default/V1.0.0__create_fruits.sql</code>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="sql" class="language-sql hljs">CREATE SEQUENCE known_fruits_id_seq;
SELECT setval('known_fruits_id_seq', 3);
CREATE TABLE known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO known_fruits(id, name) VALUES (1, 'Cherry');
INSERT INTO known_fruits(id, name) VALUES (2, 'Apple');
INSERT INTO known_fruits(id, name) VALUES (3, 'Banana');</code></pre>
</div>
</div>
<div class="paragraph">
<p>Mycompany schema (<code>src/main/resources/database/mycompany/V1.0.0__create_fruits.sql</code>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="sql" class="language-sql hljs">CREATE SEQUENCE known_fruits_id_seq;
SELECT setval('known_fruits_id_seq', 3);
CREATE TABLE known_fruits
(
  id   INT,
  name VARCHAR(40)
);
INSERT INTO known_fruits(id, name) VALUES (1, 'Avocado');
INSERT INTO known_fruits(id, name) VALUES (2, 'Apricots');
INSERT INTO known_fruits(id, name) VALUES (3, 'Blackberries');</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="programmatically-resolving-tenants-connections"><a class="anchor" href="#programmatically-resolving-tenants-connections"></a>Programmatically Resolving Tenants Connections</h3>
<div class="paragraph">
<p>If you need a more dynamic configuration for the different tenants you want to support and don&#8217;t want to end up with multiple entries in your configuration file, you can use the <code>io.quarkus.hibernate.orm.runtime.tenant.TenantConnectionResolver</code> interface to implement your own logic for retrieving a connection. Creating an application scoped bean that implements this interface will replace the current Quarkus default implementation <code>io.quarkus.hibernate.orm.runtime.tenant.DataSourceTenantConnectionResolver</code>. Your custom connection resolver would allow for example to read tenant information from a database and create a connection per tenant at runtime based on it.</p>
</div>
</div>
</div>
</div>
    </div>
  </div>
</div>

  </div>

  <div class="content project-footer">
  <div class="footer-section">
    <div class="logo-wrapper">
      <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_reverse.svg" class="project-logo" title="Quarkus"></a>
    </div>
  </div>
  <div class="grid-wrapper">
    <p class="grid__item width-3-12">Quarkus is open. All dependencies of this project are available under the <a href='https://www.apache.org/licenses/LICENSE-2.0' target='_blank'>Apache Software License 2.0</a> or compatible license.<br /><br />This website was built with <a href='https://jekyllrb.com/' target='_blank'>Jekyll</a>, is hosted on <a href='https://pages.github.com/' target='_blank'>Github Pages</a> and is completely open source. If you want to make it better, <a href='https://github.com/quarkusio/quarkusio.github.io' target='_blank'>fork the website</a> and show us what you’ve got.</p>

    
      <div class="width-1-12 project-links">
        <span>Navigation</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="/">Home</a></li>
          
            <li><a href="/guides">Guides</a></li>
          
            <li><a href="/community/#contributing">Contribute</a></li>
          
            <li><a href="/faq">FAQ</a></li>
          
            <li><a href="/get-started">Get Started</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Contribute</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://twitter.com/quarkusio">Follow us</a></li>
          
            <li><a href="https://github.com/quarkusio">GitHub</a></li>
          
            <li><a href="/security">Security&nbsp;policy</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Get Help</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://groups.google.com/forum/#!forum/quarkus-dev">Forums</a></li>
          
            <li><a href="https://quarkusio.zulipchat.com">Chatroom</a></li>
          
        </ul>
      </div>
    

    
      <div class="width-3-12 more-links">
        <span>Quarkus is made of community projects</span>
        <ul class="footer-links">
          
            <li><a href="https://vertx.io/" target="_blank">Eclipse Vert.x</a></li>
          
            <li><a href="https://microprofile.io" target="_blank">Eclipse MicroProfile</a></li>
          
            <li><a href="https://hibernate.org" target="_blank">Hibernate</a></li>
          
            <li><a href="https://netty.io" target="_blank">Netty</a></li>
          
            <li><a href="https://resteasy.github.io" target="_blank">RESTEasy</a></li>
          
            <li><a href="https://camel.apache.org" target="_blank">Apache Camel</a></li>
          
            <li><a href="https://code.quarkus.io/" target="_blank">And many more...</a></li>
          
        </ul>
      </div>
    
  </div>
</div>
  <div class="content redhat-footer">
  <div class="grid-wrapper">
    <span class="licence">
      <i class="fab fa-creative-commons"></i><i class="fab fa-creative-commons-by"></i> <a href="https://creativecommons.org/licenses/by/3.0/" target="_blank">CC by 3.0</a> | <a href="https://www.redhat.com/en/about/privacy-policy">Privacy Policy</a>
    </span>
    <span class="redhat">
      Sponsored by
    </span>
    <span class="redhat-logo">
      <a href="https://www.redhat.com/" target="_blank"><img src="/assets/images/redhat_reversed.svg"></a>
    </span>
  </div>
</div>


  <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js" integrity="sha384-8gBf6Y4YYq7Jx97PIqmTwLPin4hxIzQw5aDmUg/DDhul9fFpbbLcLh3nTIIDJKhx" crossorigin="anonymous"></script>
  <script type="text/javascript" src="/assets/javascript/mobile-nav.js"></script>
  <script type="text/javascript" src="/assets/javascript/scroll-down.js"></script>
  <script src="/assets/javascript/satellite.js" type="text/javascript"></script>
  <script src="https://quarkus.io/guides/javascript/config.js" type="text/javascript"></script>
  <script src="/assets/javascript/search-filter.js" type="text/javascript"></script>
  <script src="/assets/javascript/back-to-top.js" type="text/javascript"></script>
</body>

</html>
